home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / status.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  29.6 KB  |  1,016 lines
  1. /*
  2.  * purple
  3.  *
  4.  * Purple is the legal property of its developers, whose names are too numerous
  5.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  6.  * source distribution.
  7.  *
  8.  * This program is free software; you can redistribute it and/or modify
  9.  * it under the terms of the GNU General Public License as published by
  10.  * the Free Software Foundation; either version 2 of the License, or
  11.  * (at your option) any later version.
  12.  *
  13.  * This program is distributed in the hope that it will be useful,
  14.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16.  * GNU General Public License for more details.
  17.  *
  18.  * You should have received a copy of the GNU General Public License
  19.  * along with this program; if not, write to the Free Software
  20.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21.  */
  22. #ifndef _PURPLE_STATUS_H_
  23. #define _PURPLE_STATUS_H_
  24.  
  25. /**
  26.  * @file status.h Status API
  27.  * @ingroup core
  28.  *
  29.  * A brief explanation of the status API:
  30.  *
  31.  * PurpleStatusType's are created by each PRPL.  They outline the
  32.  * available statuses of the protocol.  AIM, for example, supports
  33.  * an available state with an optional available message, an away
  34.  * state with a mandatory message, and an invisible state (which is
  35.  * technically "independent" of the other two, but we'll get into
  36.  * that later).  PurpleStatusTypes are very permanent.  They are
  37.  * hardcoded in each PRPL and will not change often.  And because
  38.  * they are hardcoded, they do not need to be saved to any XML file.
  39.  *
  40.  * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType.
  41.  * If you're familiar with object-oriented programming languages
  42.  * then this should be immediately clear.  Say, for example, that
  43.  * one of your AIM buddies has set himself as "away."  You have a
  44.  * PurpleBuddy node for this person in your buddy list.  Purple wants
  45.  * to mark this buddy as "away," so it creates a new PurpleStatus.
  46.  * The PurpleStatus has its PurpleStatusType set to the "away" state
  47.  * for the oscar PRPL.  The PurpleStatus also contains the buddy's
  48.  * away message.  PurpleStatuses are sometimes saved, depending on
  49.  * the context.  The current PurpleStatuses associated with each of
  50.  * your accounts are saved so that the next time you start Purple,
  51.  * your accounts will be set to their last known statuses.  There
  52.  * is also a list of saved statuses that are written to the
  53.  * status.xml file.  Also, each PurpleStatus has a "savable" boolean.
  54.  * If "savable" is set to FALSE then the status is NEVER saved.
  55.  * All PurpleStatuses should be inside a PurplePresence.
  56.  *
  57.  *
  58.  * A PurpleStatus is either "indepedent" or "exclusive."
  59.  * Independent statuses can be active or inactive and it doesn't
  60.  * affect anything else.  However, you can only have one exclusive
  61.  * status per PurplePresence.  If you activate one exlusive status,
  62.  * then the previous exclusive status is automatically deactivated.
  63.  *
  64.  * A PurplePresence is like a collection of PurpleStatuses (plus some
  65.  * other random info).  For any buddy, or for any one of your accounts,
  66.  * or for any person you're chatting with, you may know various
  67.  * amounts of information.  This information is all contained in
  68.  * one PurplePresence.  If one of your buddies is away and idle,
  69.  * then the presence contains the PurpleStatus for their awayness,
  70.  * and it contains their current idle time.  PurplePresences are
  71.  * never saved to disk.  The information they contain is only relevent
  72.  * for the current PurpleSession.
  73.  */
  74.  
  75. typedef struct _PurpleStatusType      PurpleStatusType;
  76. typedef struct _PurpleStatusAttr      PurpleStatusAttr;
  77. typedef struct _PurplePresence        PurplePresence;
  78. typedef struct _PurpleStatus          PurpleStatus;
  79.  
  80. /**
  81.  * A context for a presence.
  82.  *
  83.  * The context indicates what the presence applies to.
  84.  */
  85. typedef enum
  86. {
  87.     PURPLE_PRESENCE_CONTEXT_UNSET   = 0,
  88.     PURPLE_PRESENCE_CONTEXT_ACCOUNT,
  89.     PURPLE_PRESENCE_CONTEXT_CONV,
  90.     PURPLE_PRESENCE_CONTEXT_BUDDY
  91.  
  92. } PurplePresenceContext;
  93.  
  94. /**
  95.  * A primitive defining the basic structure of a status type.
  96.  */
  97. typedef enum
  98. {
  99.     PURPLE_STATUS_UNSET = 0,
  100.     PURPLE_STATUS_OFFLINE,
  101.     PURPLE_STATUS_AVAILABLE,
  102.     PURPLE_STATUS_UNAVAILABLE,
  103.     PURPLE_STATUS_INVISIBLE,
  104.     PURPLE_STATUS_AWAY,
  105.     PURPLE_STATUS_EXTENDED_AWAY,
  106.     PURPLE_STATUS_MOBILE,
  107.     PURPLE_STATUS_NUM_PRIMITIVES
  108.  
  109. } PurpleStatusPrimitive;
  110.  
  111. #include "account.h"
  112. #include "blist.h"
  113. #include "conversation.h"
  114. #include "value.h"
  115.  
  116. #ifdef __cplusplus
  117. extern "C" {
  118. #endif
  119.  
  120. /**************************************************************************/
  121. /** @name PurpleStatusPrimitive API                                         */
  122. /**************************************************************************/
  123. /*@{*/
  124.  
  125. /**
  126.  * Lookup the id of a primitive status type based on the type.  This
  127.  * ID is a unique plain-text name of the status, without spaces.
  128.  *
  129.  * @param type A primitive status type.
  130.  *
  131.  * @return The unique ID for this type.
  132.  */
  133. const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type);
  134.  
  135. /**
  136.  * Lookup the name of a primitive status type based on the type.  This
  137.  * name is the plain-English name of the status type.  It is usually one
  138.  * or two words.
  139.  *
  140.  * @param type A primitive status type.
  141.  *
  142.  * @return The name of this type, suitable for users to see.
  143.  */
  144. const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type);
  145.  
  146. /**
  147.  * Lookup the value of a primitive status type based on the id.  The
  148.  * ID is a unique plain-text name of the status, without spaces.
  149.  *
  150.  * @param id The unique ID of a primitive status type.
  151.  *
  152.  * @return The PurpleStatusPrimitive value.
  153.  */
  154. PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id);
  155.  
  156. /*@}*/
  157.  
  158. /**************************************************************************/
  159. /** @name PurpleStatusType API                                              */
  160. /**************************************************************************/
  161. /*@{*/
  162.  
  163. /**
  164.  * Creates a new status type.
  165.  *
  166.  * @param primitive     The primitive status type.
  167.  * @param id            The ID of the status type, or @c NULL to use the id of
  168.  *                      the primitive status type.
  169.  * @param name          The name presented to the user, or @c NULL to use the
  170.  *                      name of the primitive status type.
  171.  * @param saveable      TRUE if the information set for this status by the
  172.  *                      user can be saved for future sessions.
  173.  * @param user_settable TRUE if this is a status the user can manually set.
  174.  * @param independent   TRUE if this is an independent (non-exclusive)
  175.  *                      status type.
  176.  *
  177.  * @return A new status type.
  178.  */
  179. PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive,
  180.                                           const char *id, const char *name,
  181.                                           gboolean saveable,
  182.                                           gboolean user_settable,
  183.                                           gboolean independent);
  184.  
  185. /**
  186.  * Creates a new status type with some default values (not
  187.  * savable and not independent).
  188.  *
  189.  * @param primitive     The primitive status type.
  190.  * @param id            The ID of the status type, or @c NULL to use the id of
  191.  *                      the primitive status type.
  192.  * @param name          The name presented to the user, or @c NULL to use the
  193.  *                      name of the primitive status type.
  194.  * @param user_settable TRUE if this is a status the user can manually set.
  195.  *
  196.  * @return A new status type.
  197.  */
  198. PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive,
  199.                                      const char *id, const char *name,
  200.                                      gboolean user_settable);
  201.  
  202. /**
  203.  * Creates a new status type with attributes.
  204.  *
  205.  * @param primitive     The primitive status type.
  206.  * @param id            The ID of the status type, or @c NULL to use the id of
  207.  *                      the primitive status type.
  208.  * @param name          The name presented to the user, or @c NULL to use the
  209.  *                      name of the primitive status type.
  210.  * @param saveable      TRUE if the information set for this status by the
  211.  *                      user can be saved for future sessions.
  212.  * @param user_settable TRUE if this is a status the user can manually set.
  213.  * @param independent   TRUE if this is an independent (non-exclusive)
  214.  *                      status type.
  215.  * @param attr_id       The ID of the first attribute.
  216.  * @param attr_name     The name of the first attribute.
  217.  * @param attr_value    The value type of the first attribute attribute.
  218.  * @param ...           Additional attribute information.
  219.  *
  220.  * @return A new status type.
  221.  */
  222. PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive,
  223.                                                 const char *id,
  224.                                                 const char *name,
  225.                                                 gboolean saveable,
  226.                                                 gboolean user_settable,
  227.                                                 gboolean independent,
  228.                                                 const char *attr_id,
  229.                                                 const char *attr_name,
  230.                                                 PurpleValue *attr_value, ...);
  231.  
  232. /**
  233.  * Destroys a status type.
  234.  *
  235.  * @param status_type The status type to destroy.
  236.  */
  237. void purple_status_type_destroy(PurpleStatusType *status_type);
  238.  
  239. /**
  240.  * Sets a status type's primary attribute.
  241.  *
  242.  * The value for the primary attribute is used as the description for
  243.  * the particular status type. An example is an away message. The message
  244.  * would be the primary attribute.
  245.  *
  246.  * @param status_type The status type.
  247.  * @param attr_id     The ID of the primary attribute.
  248.  */
  249. void purple_status_type_set_primary_attr(PurpleStatusType *status_type,
  250.                                        const char *attr_id);
  251.  
  252. /**
  253.  * Adds an attribute to a status type.
  254.  *
  255.  * @param status_type The status type to add the attribute to.
  256.  * @param id          The ID of the attribute.
  257.  * @param name        The name presented to the user.
  258.  * @param value       The value type of this attribute.
  259.  */
  260. void purple_status_type_add_attr(PurpleStatusType *status_type, const char *id,
  261.                                const char *name, PurpleValue *value);
  262.  
  263. /**
  264.  * Adds multiple attributes to a status type.
  265.  *
  266.  * @param status_type The status type to add the attribute to.
  267.  * @param id          The ID of the first attribute.
  268.  * @param name        The description of the first attribute.
  269.  * @param value       The value type of the first attribute attribute.
  270.  * @param ...         Additional attribute information.
  271.  */
  272. void purple_status_type_add_attrs(PurpleStatusType *status_type, const char *id,
  273.                                 const char *name, PurpleValue *value, ...);
  274.  
  275. /**
  276.  * Adds multiple attributes to a status type using a va_list.
  277.  *
  278.  * @param status_type The status type to add the attribute to.
  279.  * @param args        The va_list of attributes.
  280.  */
  281. void purple_status_type_add_attrs_vargs(PurpleStatusType *status_type,
  282.                                       va_list args);
  283.  
  284. /**
  285.  * Returns the primitive type of a status type.
  286.  *
  287.  * @param status_type The status type.
  288.  *
  289.  * @return The primitive type of the status type.
  290.  */
  291. PurpleStatusPrimitive purple_status_type_get_primitive(
  292.     const PurpleStatusType *status_type);
  293.  
  294. /**
  295.  * Returns the ID of a status type.
  296.  *
  297.  * @param status_type The status type.
  298.  *
  299.  * @return The ID of the status type.
  300.  */
  301. const char *purple_status_type_get_id(const PurpleStatusType *status_type);
  302.  
  303. /**
  304.  * Returns the name of a status type.
  305.  *
  306.  * @param status_type The status type.
  307.  *
  308.  * @return The name of the status type.
  309.  */
  310. const char *purple_status_type_get_name(const PurpleStatusType *status_type);
  311.  
  312. /**
  313.  * Returns whether or not the status type is saveable.
  314.  *
  315.  * @param status_type The status type.
  316.  *
  317.  * @return TRUE if user-defined statuses based off this type are saveable.
  318.  *         FALSE otherwise.
  319.  */
  320. gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type);
  321.  
  322. /**
  323.  * Returns whether or not the status type can be set or modified by the
  324.  * user.
  325.  *
  326.  * @param status_type The status type.
  327.  *
  328.  * @return TRUE if the status type can be set or modified by the user.
  329.  *         FALSE if it's a protocol-set setting.
  330.  */
  331. gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type);
  332.  
  333. /**
  334.  * Returns whether or not the status type is independent.
  335.  *
  336.  * Independent status types are non-exclusive. If other status types on
  337.  * the same hierarchy level are set, this one will not be affected.
  338.  *
  339.  * @param status_type The status type.
  340.  *
  341.  * @return TRUE if the status type is independent, or FALSE otherwise.
  342.  */
  343. gboolean purple_status_type_is_independent(const PurpleStatusType *status_type);
  344.  
  345. /**
  346.  * Returns whether the status type is exclusive.
  347.  *
  348.  * @param status_type The status type.
  349.  *
  350.  * @return TRUE if the status type is exclusive, FALSE otherwise.
  351.  */
  352. gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type);
  353.  
  354. /**
  355.  * Returns whether or not a status type is available.
  356.  *
  357.  * Available status types are online and possibly invisible, but not away.
  358.  *
  359.  * @param status_type The status type.
  360.  *
  361.  * @return TRUE if the status is available, or FALSE otherwise.
  362.  */
  363. gboolean purple_status_type_is_available(const PurpleStatusType *status_type);
  364.  
  365. /**
  366.  * Returns a status type's primary attribute ID.
  367.  *
  368.  * @param type The status type.
  369.  *
  370.  * @return The primary attribute's ID.
  371.  */
  372. const char *purple_status_type_get_primary_attr(const PurpleStatusType *type);
  373.  
  374. /**
  375.  * Returns the attribute with the specified ID.
  376.  *
  377.  * @param status_type The status type containing the attribute.
  378.  * @param id          The ID of the desired attribute.
  379.  *
  380.  * @return The attribute, if found. NULL otherwise.
  381.  */
  382. PurpleStatusAttr *purple_status_type_get_attr(const PurpleStatusType *status_type,
  383.                                           const char *id);
  384.  
  385. /**
  386.  * Returns a list of all attributes in a status type.
  387.  *
  388.  * @param status_type The status type.
  389.  *
  390.  * @return The list of attributes.
  391.  */
  392. const GList *purple_status_type_get_attrs(const PurpleStatusType *status_type);
  393.  
  394. /**
  395.  * Find the PurpleStatusType with the given id.
  396.  *
  397.  * @param status_types A list of status types.  Often account->status_types.
  398.  * @param id The unique ID of the status type you wish to find.
  399.  *
  400.  * @return The status type with the given ID, or NULL if one could
  401.  *         not be found.
  402.  */
  403. const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
  404.                                                     const char *id);
  405.  
  406. /*@}*/
  407.  
  408. /**************************************************************************/
  409. /** @name PurpleStatusAttr API                                              */
  410. /**************************************************************************/
  411. /*@{*/
  412.  
  413. /**
  414.  * Creates a new status attribute.
  415.  *
  416.  * @param id         The ID of the attribute.
  417.  * @param name       The name presented to the user.
  418.  * @param value_type The type of data contained in the attribute.
  419.  *
  420.  * @return A new status attribute.
  421.  */
  422. PurpleStatusAttr *purple_status_attr_new(const char *id, const char *name,
  423.                                      PurpleValue *value_type);
  424.  
  425. /**
  426.  * Destroys a status attribute.
  427.  *
  428.  * @param attr The status attribute to destroy.
  429.  */
  430. void purple_status_attr_destroy(PurpleStatusAttr *attr);
  431.  
  432. /**
  433.  * Returns the ID of a status attribute.
  434.  *
  435.  * @param attr The status attribute.
  436.  *
  437.  * @return The status attribute's ID.
  438.  */
  439. const char *purple_status_attr_get_id(const PurpleStatusAttr *attr);
  440.  
  441. /**
  442.  * Returns the name of a status attribute.
  443.  *
  444.  * @param attr The status attribute.
  445.  *
  446.  * @return The status attribute's name.
  447.  */
  448. const char *purple_status_attr_get_name(const PurpleStatusAttr *attr);
  449.  
  450. /**
  451.  * Returns the value of a status attribute.
  452.  *
  453.  * @param attr The status attribute.
  454.  *
  455.  * @return The status attribute's value.
  456.  */
  457. PurpleValue *purple_status_attr_get_value(const PurpleStatusAttr *attr);
  458.  
  459. /*@}*/
  460.  
  461. /**************************************************************************/
  462. /** @name PurpleStatus API                                                  */
  463. /**************************************************************************/
  464. /*@{*/
  465.  
  466. /**
  467.  * Creates a new status.
  468.  *
  469.  * @param status_type The type of status.
  470.  * @param presence    The parent presence.
  471.  *
  472.  * @return The new status.
  473.  */
  474. PurpleStatus *purple_status_new(PurpleStatusType *status_type,
  475.                             PurplePresence *presence);
  476.  
  477. /**
  478.  * Destroys a status.
  479.  *
  480.  * @param status The status to destroy.
  481.  */
  482. void purple_status_destroy(PurpleStatus *status);
  483.  
  484. /**
  485.  * Sets whether or not a status is active.
  486.  *
  487.  * This should only be called by the account, conversation, and buddy APIs.
  488.  *
  489.  * @param status The status.
  490.  * @param active The active state.
  491.  */
  492. void purple_status_set_active(PurpleStatus *status, gboolean active);
  493.  
  494. /**
  495.  * Sets whether or not a status is active.
  496.  *
  497.  * This should only be called by the account, conversation, and buddy APIs.
  498.  *
  499.  * @param status The status.
  500.  * @param active The active state.
  501.  * @param args   A list of attributes to set on the status.  This list is
  502.  *               composed of key/value pairs, where each key is a valid
  503.  *               attribute name for this PurpleStatusType.  The list should
  504.  *               be NULL terminated.
  505.  */
  506. void purple_status_set_active_with_attrs(PurpleStatus *status, gboolean active,
  507.                                        va_list args);
  508.  
  509. /**
  510.  * Sets whether or not a status is active.
  511.  *
  512.  * This should only be called by the account, conversation, and buddy APIs.
  513.  *
  514.  * @param status The status.
  515.  * @param active The active state.
  516.  * @param attrs  A list of attributes to set on the status.  This list is
  517.  *               composed of key/value pairs, where each key is a valid
  518.  *               attribute name for this PurpleStatusType.
  519.  */
  520. void purple_status_set_active_with_attrs_list(PurpleStatus *status, gboolean active,
  521.                                             const GList *attrs);
  522.  
  523. /**
  524.  * Sets the boolean value of an attribute in a status with the specified ID.
  525.  *
  526.  * @param status The status.
  527.  * @param id     The attribute ID.
  528.  * @param value  The boolean value.
  529.  */
  530. void purple_status_set_attr_boolean(PurpleStatus *status, const char *id,
  531.                                   gboolean value);
  532.  
  533. /**
  534.  * Sets the integer value of an attribute in a status with the specified ID.
  535.  *
  536.  * @param status The status.
  537.  * @param id     The attribute ID.
  538.  * @param value  The integer value.
  539.  */
  540. void purple_status_set_attr_int(PurpleStatus *status, const char *id,
  541.                               int value);
  542.  
  543. /**
  544.  * Sets the string value of an attribute in a status with the specified ID.
  545.  *
  546.  * @param status The status.
  547.  * @param id     The attribute ID.
  548.  * @param value  The string value.
  549.  */
  550. void purple_status_set_attr_string(PurpleStatus *status, const char *id,
  551.                                  const char *value);
  552.  
  553. /**
  554.  * Returns the status's type.
  555.  *
  556.  * @param status The status.
  557.  *
  558.  * @return The status's type.
  559.  */
  560. PurpleStatusType *purple_status_get_type(const PurpleStatus *status);
  561.  
  562. /**
  563.  * Returns the status's presence.
  564.  *
  565.  * @param status The status.
  566.  *
  567.  * @return The status's presence.
  568.  */
  569. PurplePresence *purple_status_get_presence(const PurpleStatus *status);
  570.  
  571. /**
  572.  * Returns the status's type ID.
  573.  *
  574.  * This is a convenience method for
  575.  * purple_status_type_get_id(purple_status_get_type(status)).
  576.  *
  577.  * @param status The status.
  578.  *
  579.  * @return The status's ID.
  580.  */
  581. const char *purple_status_get_id(const PurpleStatus *status);
  582.  
  583. /**
  584.  * Returns the status's name.
  585.  *
  586.  * This is a convenience method for
  587.  * purple_status_type_get_name(purple_status_get_type(status)).
  588.  *
  589.  * @param status The status.
  590.  *
  591.  * @return The status's name.
  592.  */
  593. const char *purple_status_get_name(const PurpleStatus *status);
  594.  
  595. /**
  596.  * Returns whether or not a status is independent.
  597.  *
  598.  * This is a convenience method for
  599.  * purple_status_type_is_independent(purple_status_get_type(status)).
  600.  *
  601.  * @param status The status.
  602.  *
  603.  * @return TRUE if the status is independent, or FALSE otherwise.
  604.  */
  605. gboolean purple_status_is_independent(const PurpleStatus *status);
  606.  
  607. /**
  608.  * Returns whether or not a status is exclusive.
  609.  *
  610.  * This is a convenience method for
  611.  * purple_status_type_is_exclusive(purple_status_get_type(status)).
  612.  *
  613.  * @param status The status.
  614.  *
  615.  * @return TRUE if the status is exclusive, FALSE otherwise.
  616.  */
  617. gboolean purple_status_is_exclusive(const PurpleStatus *status);
  618.  
  619. /**
  620.  * Returns whether or not a status is available.
  621.  *
  622.  * Available statuses are online and possibly invisible, but not away or idle.
  623.  *
  624.  * This is a convenience method for
  625.  * purple_status_type_is_available(purple_status_get_type(status)).
  626.  *
  627.  * @param status The status.
  628.  *
  629.  * @return TRUE if the status is available, or FALSE otherwise.
  630.  */
  631. gboolean purple_status_is_available(const PurpleStatus *status);
  632.  
  633. /**
  634.  * Returns the active state of a status.
  635.  *
  636.  * @param status The status.
  637.  *
  638.  * @return The active state of the status.
  639.  */
  640. gboolean purple_status_is_active(const PurpleStatus *status);
  641.  
  642. /**
  643.  * Returns whether or not a status is considered 'online'
  644.  *
  645.  * @param status The status.
  646.  *
  647.  * @return TRUE if the status is considered online, FALSE otherwise
  648.  */
  649. gboolean purple_status_is_online(const PurpleStatus *status);
  650.  
  651. /**
  652.  * Returns the value of an attribute in a status with the specified ID.
  653.  *
  654.  * @param status The status.
  655.  * @param id     The attribute ID.
  656.  *
  657.  * @return The value of the attribute.
  658.  */
  659. PurpleValue *purple_status_get_attr_value(const PurpleStatus *status,
  660.                                       const char *id);
  661.  
  662. /**
  663.  * Returns the boolean value of an attribute in a status with the specified ID.
  664.  *
  665.  * @param status The status.
  666.  * @param id     The attribute ID.
  667.  *
  668.  * @return The boolean value of the attribute.
  669.  */
  670. gboolean purple_status_get_attr_boolean(const PurpleStatus *status,
  671.                                       const char *id);
  672.  
  673. /**
  674.  * Returns the integer value of an attribute in a status with the specified ID.
  675.  *
  676.  * @param status The status.
  677.  * @param id     The attribute ID.
  678.  *
  679.  * @return The integer value of the attribute.
  680.  */
  681. int purple_status_get_attr_int(const PurpleStatus *status, const char *id);
  682.  
  683. /**
  684.  * Returns the string value of an attribute in a status with the specified ID.
  685.  *
  686.  * @param status The status.
  687.  * @param id     The attribute ID.
  688.  *
  689.  * @return The string value of the attribute.
  690.  */
  691. const char *purple_status_get_attr_string(const PurpleStatus *status,
  692.                                         const char *id);
  693.  
  694. /**
  695.  * Compares two statuses for availability.
  696.  *
  697.  * @param status1 The first status.
  698.  * @param status2 The second status.
  699.  *
  700.  * @return -1 if @a status1 is more available than @a status2.
  701.  *          0 if @a status1 is equal to @a status2.
  702.  *          1 if @a status2 is more available than @a status1.
  703.  */
  704. gint purple_status_compare(const PurpleStatus *status1, const PurpleStatus *status2);
  705.  
  706. /*@}*/
  707.  
  708. /**************************************************************************/
  709. /** @name PurplePresence API                                                */
  710. /**************************************************************************/
  711. /*@{*/
  712.  
  713. /**
  714.  * Creates a new presence.
  715.  *
  716.  * @param context The presence context.
  717.  *
  718.  * @return A new presence.
  719.  */
  720. PurplePresence *purple_presence_new(PurplePresenceContext context);
  721.  
  722. /**
  723.  * Creates a presence for an account.
  724.  *
  725.  * @param account The account.
  726.  *
  727.  * @return The new presence.
  728.  */
  729. PurplePresence *purple_presence_new_for_account(PurpleAccount *account);
  730.  
  731. /**
  732.  * Creates a presence for a conversation.
  733.  *
  734.  * @param conv The conversation.
  735.  *
  736.  * @return The new presence.
  737.  */
  738. PurplePresence *purple_presence_new_for_conv(PurpleConversation *conv);
  739.  
  740. /**
  741.  * Creates a presence for a buddy.
  742.  *
  743.  * @param buddy The buddy.
  744.  *
  745.  * @return The new presence.
  746.  */
  747. PurplePresence *purple_presence_new_for_buddy(PurpleBuddy *buddy);
  748.  
  749. /**
  750.  * Destroys a presence.
  751.  *
  752.  * All statuses added to this list will be destroyed along with
  753.  * the presence.
  754.  *
  755.  * @param presence The presence to destroy.
  756.  */
  757. void purple_presence_destroy(PurplePresence *presence);
  758.  
  759. /**
  760.  * Adds a status to a presence.
  761.  *
  762.  * @param presence The presence.
  763.  * @param status   The status to add.
  764.  */
  765. void purple_presence_add_status(PurplePresence *presence, PurpleStatus *status);
  766.  
  767. /**
  768.  * Adds a list of statuses to the presence.
  769.  *
  770.  * @param presence    The presence.
  771.  * @param source_list The source list of statuses to add.
  772.  */
  773. void purple_presence_add_list(PurplePresence *presence, const GList *source_list);
  774.  
  775. /**
  776.  * Sets the active state of a status in a presence.
  777.  *
  778.  * Only independent statuses can be set unactive. Normal statuses can only
  779.  * be set active, so if you wish to disable a status, set another
  780.  * non-independent status to active, or use purple_presence_switch_status().
  781.  *
  782.  * @param presence  The presence.
  783.  * @param status_id The ID of the status.
  784.  * @param active    The active state.
  785.  */
  786. void purple_presence_set_status_active(PurplePresence *presence,
  787.                                      const char *status_id, gboolean active);
  788.  
  789. /**
  790.  * Switches the active status in a presence.
  791.  *
  792.  * This is similar to purple_presence_set_status_active(), except it won't
  793.  * activate independent statuses.
  794.  *
  795.  * @param presence The presence.
  796.  * @param status_id The status ID to switch to.
  797.  */
  798. void purple_presence_switch_status(PurplePresence *presence,
  799.                                  const char *status_id);
  800.  
  801. /**
  802.  * Sets the idle state and time on a presence.
  803.  *
  804.  * @param presence  The presence.
  805.  * @param idle      The idle state.
  806.  * @param idle_time The idle time, if @a idle is TRUE.  This
  807.  *                  is the time at which the user became idle,
  808.  *                  in seconds since the epoch.
  809.  */
  810. void purple_presence_set_idle(PurplePresence *presence, gboolean idle,
  811.                             time_t idle_time);
  812.  
  813. /**
  814.  * Sets the login time on a presence.
  815.  *
  816.  * @param presence   The presence.
  817.  * @param login_time The login time.
  818.  */
  819. void purple_presence_set_login_time(PurplePresence *presence, time_t login_time);
  820.  
  821.  
  822. /**
  823.  * Returns the presence's context.
  824.  *
  825.  * @param presence The presence.
  826.  *
  827.  * @return The presence's context.
  828.  */
  829. PurplePresenceContext purple_presence_get_context(const PurplePresence *presence);
  830.  
  831. /**
  832.  * Returns a presence's account.
  833.  *
  834.  * @param presence The presence.
  835.  *
  836.  * @return The presence's account.
  837.  */
  838. PurpleAccount *purple_presence_get_account(const PurplePresence *presence);
  839.  
  840. /**
  841.  * Returns a presence's conversation.
  842.  *
  843.  * @param presence The presence.
  844.  *
  845.  * @return The presence's conversation.
  846.  */
  847. PurpleConversation *purple_presence_get_conversation(const PurplePresence *presence);
  848.  
  849. /**
  850.  * Returns a presence's chat user.
  851.  *
  852.  * @param presence The presence.
  853.  *
  854.  * @return The chat's user.
  855.  */
  856. const char *purple_presence_get_chat_user(const PurplePresence *presence);
  857.  
  858. /**
  859.  * Returns the presence's buddy.
  860.  *
  861.  * @param presence The presence.
  862.  *
  863.  * @return The presence's buddy.
  864.  */
  865. PurpleBuddy *purple_presence_get_buddy(const PurplePresence *presence);
  866.  
  867. /**
  868.  * Returns all the statuses in a presence.
  869.  *
  870.  * @param presence The presence.
  871.  *
  872.  * @return The statuses.
  873.  */
  874. const GList *purple_presence_get_statuses(const PurplePresence *presence);
  875.  
  876. /**
  877.  * Returns the status with the specified ID from a presence.
  878.  *
  879.  * @param presence  The presence.
  880.  * @param status_id The ID of the status.
  881.  *
  882.  * @return The status if found, or NULL.
  883.  */
  884. PurpleStatus *purple_presence_get_status(const PurplePresence *presence,
  885.                                      const char *status_id);
  886.  
  887. /**
  888.  * Returns the active exclusive status from a presence.
  889.  *
  890.  * @param presence The presence.
  891.  *
  892.  * @return The active exclusive status.
  893.  */
  894. PurpleStatus *purple_presence_get_active_status(const PurplePresence *presence);
  895.  
  896. /**
  897.  * Returns whether or not a presence is available.
  898.  *
  899.  * Available presences are online and possibly invisible, but not away or idle.
  900.  *
  901.  * @param presence The presence.
  902.  *
  903.  * @return TRUE if the presence is available, or FALSE otherwise.
  904.  */
  905. gboolean purple_presence_is_available(const PurplePresence *presence);
  906.  
  907. /**
  908.  * Returns whether or not a presence is online.
  909.  *
  910.  * @param presence The presence.
  911.  *
  912.  * @return TRUE if the presence is online, or FALSE otherwise.
  913.  */
  914. gboolean purple_presence_is_online(const PurplePresence *presence);
  915.  
  916. /**
  917.  * Returns whether or not a status in a presence is active.
  918.  *
  919.  * A status is active if itself or any of its sub-statuses are active.
  920.  *
  921.  * @param presence  The presence.
  922.  * @param status_id The ID of the status.
  923.  *
  924.  * @return TRUE if the status is active, or FALSE.
  925.  */
  926. gboolean purple_presence_is_status_active(const PurplePresence *presence,
  927.                                         const char *status_id);
  928.  
  929. /**
  930.  * Returns whether or not a status with the specified primitive type
  931.  * in a presence is active.
  932.  *
  933.  * A status is active if itself or any of its sub-statuses are active.
  934.  *
  935.  * @param presence  The presence.
  936.  * @param primitive The status primitive.
  937.  *
  938.  * @return TRUE if the status is active, or FALSE.
  939.  */
  940. gboolean purple_presence_is_status_primitive_active(
  941.     const PurplePresence *presence, PurpleStatusPrimitive primitive);
  942.  
  943. /**
  944.  * Returns whether or not a presence is idle.
  945.  *
  946.  * @param presence The presence.
  947.  *
  948.  * @return TRUE if the presence is idle, or FALSE otherwise.
  949.  *         If the presence is offline (purple_presence_is_online()
  950.  *         returns FALSE) then FALSE is returned.
  951.  */
  952. gboolean purple_presence_is_idle(const PurplePresence *presence);
  953.  
  954. /**
  955.  * Returns the presence's idle time.
  956.  *
  957.  * @param presence The presence.
  958.  *
  959.  * @return The presence's idle time.
  960.  */
  961. time_t purple_presence_get_idle_time(const PurplePresence *presence);
  962.  
  963. /**
  964.  * Returns the presence's login time.
  965.  *
  966.  * @param presence The presence.
  967.  *
  968.  * @return The presence's login time.
  969.  */
  970. time_t purple_presence_get_login_time(const PurplePresence *presence);
  971.  
  972. /**
  973.  * Compares two presences for availability.
  974.  *
  975.  * @param presence1 The first presence.
  976.  * @param presence2 The second presence.
  977.  *
  978.  * @return -1 if @a presence1 is more available than @a presence2.
  979.  *          0 if @a presence1 is equal to @a presence2.
  980.  *          1 if @a presence1 is less available than @a presence2.
  981.  */
  982. gint purple_presence_compare(const PurplePresence *presence1,
  983.                            const PurplePresence *presence2);
  984.  
  985. /*@}*/
  986.  
  987. /**************************************************************************/
  988. /** @name Status subsystem                                                */
  989. /**************************************************************************/
  990. /*@{*/
  991.  
  992. /**
  993.  * Get the handle for the status subsystem.
  994.  *
  995.  * @return the handle to the status subsystem
  996.  */
  997. void *purple_status_get_handle(void);
  998.  
  999. /**
  1000.  * Initializes the status subsystem.
  1001.  */
  1002. void purple_status_init(void);
  1003.  
  1004. /**
  1005.  * Uninitializes the status subsystem.
  1006.  */
  1007. void purple_status_uninit(void);
  1008.  
  1009. /*@}*/
  1010.  
  1011. #ifdef __cplusplus
  1012. }
  1013. #endif
  1014.  
  1015. #endif /* _PURPLE_STATUS_H_ */
  1016.